fix(metadata): compute the history retention cutoff on one calendar, not two - #16060

Fixes #15824

The defect

packages/metadata/src/utils/history-cleanup.ts built its retention cutoff on the local calendar and rendered it on UTC:

const cutoffDate = new Date();
cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);   // LOCAL calendar
const cutoffISO = cutoffDate.toISOString();                          // UTC rendering
const filter = { recorded_at: { $lt: cutoffISO } };                  // a DELETE filter

setDate preserves wall-clock time, so stepping the local calendar back n days moves the instant by exactly n × 24h only while every local day in the window is 24 hours long. When the window straddles a DST transition it is 23 hours (spring-forward) or 25 (fall-back), and the cutoff instant slips by the size of that transition — one hour in most zones, thirty minutes on Lord Howe Island.

Both sites, one change

The byte-identical spelling appeared twice. Line numbers re-derived at merge base e1d4f9e3f:

Both now spell it cutoffDate.setUTCDate(cutoffDate.getUTCDate() - this.policy.maxAgeDays).

Measured blast radius

The card describes the error as "twice a year". That is exact for maxAgeDays: 1, and an understatement above it: the window only has to straddle a transition, with no second condition about crossing a UTC midnight, so the exposure grows with the retention period. Measured over a 16-zone × 366-day × 48-half-hour sweep of 2026, as the fraction of instants at which the old spelling produced a wrong cutoff:

That bottom row is why nothing in CI has ever gone red on this, and why the pin below cannot be written to run only at TZ=UTC.

The pin

packages/metadata/src/utils/history-cleanup-dst.test.ts — 27 tests, of which 16 are MEASURED DST cells, drawn from a 12-zone × 366-day × 48-half-hour × 7-maxAgeDays sweep of 2026 that found 347,539 disagreeing combinations. Both hemispheres, both transition directions, maxAgeDays from 1 to 180, three zones whose standard offset is not a whole hour (America/St_Johns −03:30, Australia/Adelaide +09:30, Pacific/Chatham +12:45), and one whose transition is not a whole hour (Australia/Lord_Howe, ±30 minutes) so a whole-hour assumption cannot hide in the fix.

Each cell fakes both halves of the environment (process.env.TZ plus a frozen clock) and carries an inline control that asserts the old mixed spelling disagrees there — evaluated before the assertion about the subject. Without it a green run would be ambiguous between "the fix works" and "these instants were not in a transition window", the second being the failure mode that hid the defect. Every cell asserts both call sites, against an oracle that is the definition of the window (instant − maxAgeDays × 86_400_000) rather than a re-implementation of the fix.

Ablation

The mutation was proven on disk before the measurement and the restore proven after, in one shell:

ABLATE: HEAD blob = c064158a6e6425f593855fbae3f025fe812928da
ABLATE: after mutation — fixed-spelling count=0 (want 0), old-spelling count=2 (want 2)
ABLATE: mutated blob = 3a9981195d408195bf22987879f4ad17f8e0361b
ABLATE: MUTATION PROVEN ON DISK
ABLATE: vitest exit under mutation = 1 (want non-zero)
    →  Tests  19 failed | 8 passed (27)
ABLATE: restored blob = c064158a6e6425f593855fbae3f025fe812928da
ABLATE: git diff HEAD -- FILE exit = 0 (want 0)
ABLATE: RESTORE PROVEN (blob == HEAD blob AND git diff HEAD empty)

All 16 measured cells reddened, plus the timezone-invariance fence and both filter-scoping fences. The 8 that stayed green are the ones that do not read the subject's spelling — the cell-table meta-assertions, the non-DST fences and the TZ-restoration fence — which is what they are for.

Fences — what this deliberately does NOT do

• It does not make retention timezone-aware. The card fences that off explicitly and it needs its own ruling. The pin asserts the opposite: for one instant and one maxAgeDays, the cutoff is now identical in every zone, DST-observing or not.
• It does not chase the preview-vs-delete disagreement. The two sites read new Date() independently, so they can straddle any boundary for that ordinary reason. That is inherent and this change does not remove it; each site is pinned against the truth separately, at one frozen instant.
• Nothing else in either filter moved. Pinned: the organization_id scoping, the ADR-0009 executionPinned $nin exclusion, the maxVersions path, and that a policy without maxAgeDays builds no age filter at all.

Published-surface reading

Clause-②: no, both limbs, re-derived rather than assumed — HistoryCleanupManager is exported public API (packages/metadata/src/index.ts:33), so the question is live.

• Limb 1 (exported symbol or signature moves): no. Built @objectstack/metadata at this head, swapped the one changed source file back to e1d4f9e3f, rebuilt, diffed the emitted dist/index.d.ts: byte-identical, git hash-object = 79b154732b61f586e182e1678c11af085c9cbadd on both sides, diff -u exit 0 / 0 lines. Source restored byte-exact afterwards and proven (blob == HEAD blob, git diff HEAD empty), and the post-restore rebuild reproduced the same d.ts hash.
• Limb 2 (accept set moves): no. MetadataHistoryRetentionPolicy is untouched; maxAgeDays still accepts exactly z.number().int().positive().optional(). What changes is the cutoff instant — an answer computed from the policy — not which inputs are accepted or rejected.

Verification

All readings below are at d2308c952, with each exit code captured before any pipe.

Gate verdict lines worth quoting:

check-nul-bytes: OK (scanned 7740 text file(s) -- 7740 tracked, 0 untracked-not-ignored;
  skipped 7 binary; no raw ASCII control bytes).
OK: 27 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
check-test-source-alias OK — 72 packages with tests scanned; 61 registered as still resolving a
  workspace dep through `dist/`; 49 published subpath(s) resolved through every alias table.
✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).
✓ This diff introduces no `major` bump.
check-dts-closure: 13 built package(s) swept - 74/74 declared declaration file(s) present.

The two exit-3 families are NOT MEASURED, in their own words, and both need a full workspace build that CI performs:

• pnpm check:dual-build-cjs-loads — self-test passed (93 cases); then PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/. … ⛔ This is NOT a pass: nothing was measured.
• pnpm check:type-check-debt — the coverage leg passed (check-type-check-coverage: OK — 75/79 workspace packages type-checked); the --re-measure leg refused: 20 workspace dependenc(ies) of the ledgered packages have no built type entry point on disk … ⛔ This is NOT a pass and NOT a finding.

Generated by Claude Code